Programming With QuickTime VR

Showing and Hiding Controller Bar Buttons

You can use standard QuickTime movie controller routines to hide and show specific buttons in the controller bar associated with a QuickTime VR movie. The QuickTime VR movie controller automatically shows and hides some buttons, and it automatically disables some buttons that might not be appropriate for a specific movie or node. You can, however, override these automatic behaviors using the QuickTime VR Manager.

For instance, the QuickTime VR movie controller displays the speaker button (used for adjusting a movie's volume) whenever a movie contains a sound track. It's possible, however, that only a single node in a large multinode movie has a sound track. In that case, you might want to hide the speaker button in all nodes that do not have a sound track. Conversely, the QuickTime VR movie controller hides the speaker button if a movie does not contain a sound track. You might, however, play a sound loaded from a sound resource or from another QuickTime file. In that case, you might want to show the speaker button and have it control the sound you're playing. In both these cases, you need to override the default behavior of the QuickTime VR movie controller.

Note first that every VR movie has two sets of movie controller flags: a set of control flags and a set of explicit flags. The control flags work as described in "Movie Control Flags" and documented in Inside Macintosh: QuickTime Components: If a bit in the set of control flags is set (that is, equal to 1), then the associated action or property is enabled. For instance, bit 17 (mcFlagQTVRSuppressZoomBtns ) means to suppress the zoom buttons. So, if that bit is set in a VR movie's control flags, the zoom buttons are not displayed. If that bit is clear, the zoom buttons are displayed.

However, the QuickTime VR movie controller sometimes suppresses buttons even when those buttons have not been explicitly suppressed in the control flags. As already mentioned, if a particular VR movie does not contain a sound track, then the movie controller automatically suppresses the speaker button. If a movie does contain a sound track, then the speaker button is displayed only if the suppress speaker bit is off.

This might not be what you'd like to happen. For instance, if your application is playing a sound that it loaded from a sound resource, you might want the user to be able to adjust the sound's volume using the volume control. To do that, you need a way to force the speaker button to appear. For this reason, the explicit flags were introduced.

The explicit flags indicate which bits in the control flags are to be used explicitly (that is, taken at face value). If a certain bit is set in a movie's explicit flags, then the corresponding bit in the control flags is interpreted as the desired setting for the feature (and the movie controller does not attempt to do anything clever). In other words, if bit 17 is set in a movie's explicit flags and bit 17 is clear in that movie's control flags, then the zoom buttons are always displayed. Similarly, if bit 2 is set in a movie's explicit flags and bit 2 is clear in that movie's control flags, then the speaker button is displayed, whether or not the movie contains a sound track.

To get or set a bit in a movie's explicit flags, you must set the flag mcFlagQTVRExplicitFlagSet in your call to mcActionGetFlags or mcActionSetFlags . To get or set a bit in a movie's control flags, you must clear the flag mcFlagQTVRExplicitFlagSet in your call to mcActionGetFlags or mcActionSetFlags . Note that when you use the defined constants to set values in the explicit flags, the constant names might be confusing. For instance, setting the bit mcFlagSuppressSpeakerButton in a movie's explicit flags doesn't cause the speaker to be suppressed; it just means: "use the actual value of the mcFlagSuppressSpeakerButton bit in the control flags."

Now you can see how to hide or show a button in the controller bar: set the appropriate explicit flag to 1 and set the corresponding control flag to the desired value. Listing 3-2 shows how to force a specific button in the controller bar to be displayed.

Listing 2 Showing a controller bar button



 
void ShowControllerButton (MovieController theMC, long theButton) 

{

    long    myControllerFlags;

    

    // Get the current explicit flags 

    // and set the explicit flag for the specified button.

    myControllerFlags = mcFlagQTVRExplicitFlagSet;

    MCDoAction(theMC, mcActionGetFlags, &myControllerFlags);

    MCDoAction(theMC, mcActionSetFlags, 

            (void *)((myControllerFlags | theButton) | mcFlagQTVRExplicitFlagSet));

    

    // Get the current control flags

    // and clear the suppress flag for the specified button.

    myControllerFlags = 0;

    MCDoAction(theMC, mcActionGetFlags, &myControllerFlags);

    MCDoAction(theMC, mcActionSetFlags, 

            (void *)(myControllerFlags & ~theButton));

}

Listing 3-3 shows how to force a specific button in the controller bar to be hidden. Because the suppress flag overrides the setting of the explicit flag, this routine sets only the suppress flag and doesn't bother with the explicit flag.

Listing 3 Hiding a controller bar button



 
void HideControllerButton (MovieController theMC, long theButton) 

{

    long    myControllerFlags;

    

    // Get the current control flags

    // and set the suppress flag for the specified button.

    myControllerFlags = 0;

    MCDoAction(theMC, mcActionGetFlags, &myControllerFlags);

    MCDoAction(theMC, mcActionSetFlags, 

            (void *)((myControllerFlags | theButton));

}